Version Control

(please sit in your project groups!)

Monday, May 8

Today we will…

  • Questions about PA 5.1, PA 5.2 or Lab 5?
  • New Material
    • git/GitHub
    • Connect GitHub to RStudio
  • PA 6: Merge Conflicts – Collaborating within a GitHub Repo
  • Discuss Group Contract
  • Questions about Midterm?

What is version control?


A process of tracking changes to a file or set of files over time so that you can recall specific versions later.

git/GitHub Basics

Git vs GitHub

  • A system for version control that manages a collection of files in a structured way.
  • Uses the command line or a GUI.
  • Git is local.

Git vs GitHub

  • A system for version control that manages a collection of files in a structured way.
  • Uses the command line or a GUI.
  • Git is local.

  • A cloud-based service that lets you use git across many computers.
  • Basic services are free, advanced services are paid (like RStudio!).
  • GitHub is remote.

Why Learn GitHub?

  1. GitHub provides a structured way for tracking changes to files over the course of a project.
  • Think Google Docs or Dropbox history, but more structured and powerful!

  1. GitHub makes it easy to have multiple people working on the same files at the same time.

  2. You can host a URL of fun things (like the class text, these slides, a personal website, etc.) with GitHub pages.

Git Repositories

Git is based on repositories.

  • Think of a repository (repo) as a directory (folder) for a single project.
    • This directory will likely contain code, documentation, data, to do lists, etc. associated with the project.
    • You can link a local repo with a remote copy.

  • To create a repository, you can start with your local computer or you can start with the remote copy.

.gitignore

Sometimes there are files that you do not want to track.

  • A .gitignore file specifies the files that git should intentionally ignore.
  • Often these are machine generated files (e.g., /bin, .DS_Store) or files/directories that you do not want to be shared (e.g., solutions/).
  • We want to ignore .Rproj files!

Actions in Git

Cloning a Repo


Create an exact copy of a remote repo on your local machine.

Committing Changes

Tell git you have made changes you want to add to the repo.

  • Also provide a commit message – a short label describing what the changes are and why they exist.

The red line is a change we commit (add) to the repo.

The log of these changes (and the file history) is called your git commit history.

  • You can always go back to old copies!

Pushing Changes


Update the copy of your repo on GitHub so it has the most recent changes you’ve made on your machine.

Pulling Changes


Update the local copy of your repo (the copy on your computer) with the version on GitHub.

Pushing and Pulling

Workflow

When you have an existing local repo:

  1. Pull the repo (especially if collaborating).
  2. Make some changes locally.
  3. Commit the changes to git.
  4. Pull any changes from the remote repository (again!).
  5. Resolve any merge conflicts.
  6. Push your changes to GitHub.

Merge Conflicts

These occur when git encounters conflicting changes.

  • You and a collaborator made conflicting changes at the same time.
  • You made changes without starting from the same “state” as the repo you are trying to combine with.

Troubleshooting Merge Conflicts

  1. Maybe you are working in real time on the same line of code or text as a collaborator.
  2. Maybe you forgot to push your changes the last time you finished working.
  3. Maybe you forgot to pull your changes before you started working this time.

We will work on resolving merge conflicts today!

Connect GitHub to RStudio

Install + Load R Packages

Work in your console or an Rscript for this.

  1. Install and load the usethis package.
install.packages("usethis")
library(usethis)
  1. Install and load the gitcreds Package.
install.packages("gitcreds")
library(gitcreds)

Configure git

  1. Tell git your email and GitHub username.
use_git_config(user.name = "JaneDoe2", user.email = "jane@example.org")

(Nothing should happen.)

Generate your Personal Access Token

  1. Generate a PAT.
create_github_token()
  • This will open GitHub and ask you to log in.
  • Fill in a Note and an Expiration (AT LEAST 60 days from now).
  • Click Generate Token.

Store your PAT

  1. Copy your PAT.

  1. Run the following code.
gitcreds_set()

When prompted to Enter password or token:, paste your PAT.

Verify your PAT

  1. Let’s verify.
git_sitrep()

PA 6: Merge Conflicts

Collaborating within a GitHub Repo

Get into your groups!

Designate each person one of the suits:

You will reference these as you work through the activity.

Warning

If you only have 3 group members here, assign one person both and .

Flags


Please put up your sticky note to indicate your group is ready to move on!

Repository Setup

Create a Repo on GitHub

  • Create a new Github repo: Repositories > New
    • Name the repo: stat331-PA6
    • You can choose Public or Private.
    • Select .gitignore template: R
  • After creating the repo, go to Settings > Collaborators > Add people
    • Add your group members using their username or email.

Access the Remote Repo

  • Accept the repo invite (in your email) – View invite > Accept invite
  • Open the repo on GitHub.

Clone the Remote Repo Locally

  • Rstudio: File > New Project > Version Control > Git
  • GitHub: click <> Code and copy the HTTPS address.
  • Rstudio: paste the address as the Repository URL.
  • Click Browse and create this new project on your desktop.
    • Do not save this in your master STAT 331 folder!!! We don’t want to embed an Rproj within another RProj.
  • Create Project

Collaborating in GitHub

Add Documents to the Repo

  • Create a new Quarto file.
    • Change the title to “Practice Activity 6”.
    • Resist the urge to add authors.
    • Save as PA6.qmd in your new stat331-PA6 folder.
    • Add self-contained: true to the YAML.
    • Render the document.
  • Edit the .gitignore file to include *.Rproj.

Push Documents to the Repo

  • Rstudio: Git pane > Commit
    • Stage (checkmark) the .gitignore, add a commit message (“ignore all .Rproj files”), click Commit, click Close.
    • Stage (checkmark) PA6.qmd and PA6.html, add a commit message (“create PA quarto file”), click Commit, click Close.
  • Rstudio: Git pane > Push the changes to the remote repo.

Pull Changes from the Repo

  • Rstudio: Git pane > Pull the changes that were made!

Everyone should now have the .qmd and .html files in their local repo!

  • Look in your Files pane.

Make a Change

  • Add author: to the YAML and include everyone’s first names.
  • Render the document.
  • Rstudio: Git pane > Commit > Stage (checkmark) files > add commit message > Commit
    • Use a commit message like “add first names”.
  • Rstudio: Git pane > Push the changes.

Forget to Pull

Do not pull the changes that were made!

Make the Same Change

  • Add author: to the YAML and include everyone’s first and last names.
  • Render the document.
  • Rstudio: Git pane > Commit > Stage (checkmark) files > add commit message > Commit
    • Use a commit message like “add first and last names”.
  • Rstudio: Git pane > Push the changes.

A Merge Conflict

You got an error! Ugh. We forgot to pull before we started making changes.

Resolve the Merge Conflict

Rstudio: Git pane > Pull the changes from the repo.

If your Git Pull window does not look like this:

  • Copy-paste the first command ( git config pull.rebase false ) into the Terminal pane and hit Enter.
  • Pull again.

Resolve the Merge Conflict

Resolve the Merge Conflict

Tip

Note how the conflicting lines are marked! You might need to submit this to Canvas…

  • Edit the .qmd file to resolve the conflict with the preferred change. Render.
  • Commit your changes.
  • Push your changes to GitHub.

Forget to Pull

Do not pull the changes that were made!

Make a Different Change

  • Eidt the first code chunk to find the product of \(13 \times 13\).
  • Render the document.
  • Commit your changes and Push your changes to GitHub.

Warning

You will get an error, read it and Pull.

  • No merge conflicts should occur! Push your changes again.

Auto Merge

Note: your merge may have been made by a different strategy. That’s okay!

Forget to Pull

Do not pull the changes that were made!

Make the Same Change (Again)

  • Eidt the first code chunk to find the product of \(11 \times 11\).
  • Render the document.
  • Commit your changes and Push your changes to GitHub.

Warning

You will get an error. Ugh!!!! We forgot to pull again!

Make the Same Change (Again)

  • Pull the changes from the repo.
  • Edit the .qmd file to resolve the conflict with the preferred change.
  • Commit your changes and Push your changes to GitHub.

Final Document

Pull the changes and look at your final document.

Canvas Quiz Submission

How does Git mark the start of lines with a merge conflict?

  • Specifically, I want the four capital characters with which every conflict is marked.

Commit Tips

  • Use short, but informative commit messages.
  • Commit small blocks of changes – commit every time you accomplish a small task.
    • You’ll have a set of bite-sized changes (with description) to serve as a record of what you’ve done.
    • With frequent commits, its easier to find the issue when you mess up or end up in a merge conflict.

Tips for Avoiding Merge Conflicts

  • Always pull before you start working and always push after you are done working!
    • If you follow this advice exactly, you will only have problems if two of you are making local changes to the same line in the same file at the same time.
  • If you are working with collaborators in real time, pull, commit, and push often.
  • Git commits lines – lines of code, lines of text, etc.
    • Practice good format and put each sentence on a line.

When all else fails…

Burn your local repo to the ground and clone again.

Final Project Group Contract

Questions about Midterm Exam?

To do…

  • PA 6: Merge Conflicts
    • Due Monday, 5/8 at 11:59pm.
  • Midterm Exam
    • Wednesday, 5/10 + 24 hours.
  • Group Contracts
    • Due Wednesday, 5/17 at 11:59pm.

Note

Extended office hours on Tuesday from 10:00 - 12:00. No office hours on Friday.

Wednesday, May 10 – Midterm Exam

  • Please grab separators from the sides of the room as you enter.

  • I will pass out a hard copy of the exam.

  • Canvas will unlock the .qmd template at the beginning of class.

Wednesday, May 10 – Midterm Exam

Section 1: General Questions

  • Cannot work on Section 2 until submitting Section 1.

Section 2: Short Answer

  • Download .qmd template from Canvas.
  • Submit .qmd and .html files on Canvas by the end of class.

Section 3: Open-Ended Analysis

  • Create your own .qmd file.
  • Submit .qmd and .html file 24-hours after the end of class.

To do…

  • Read Chapter 7: Writing Functions
    • Check-in 7.1 due Monday, 5/15 at 10:00am
  • Final Project Group Contract
    • Due Wednesday, 5/17 at 11:59pm